//+------------------------------------------------------------------+
//|                      ArrayShort.mqh 短整数数组类头文件          |
//|                版权所有 2000-2025, MetaQuotes Ltd.              |
//|                        官方网址: https://www.mql5.com            |
//+------------------------------------------------------------------+
#include "Array.h"  // 引入基础数组类头文件，CArrayShort 继承自 CArray
//+------------------------------------------------------------------+
//| CArrayShort 类                                                   |
//| 功能：用于管理 short 类型（16位短整数）的动态数组类              |
//| 核心特性：小内存占用（每个元素仅2字节），适用于存储小范围整数    |
//| 继承关系：派生自基础数组类 CArray，支持短整数的动态增删、排序、查找等操作 |
//+------------------------------------------------------------------+
class CArrayShort : public CArray
  {
protected:
   short             m_data[];           // 存储16位短整数的核心数组容器（每个元素占2字节）

public:
   /**
    * @brief 构造函数：初始化 CArrayShort 类实例
    * @details 初始化数组容量（m_data_max）、已存储元素数量（m_data_total）等成员变量，为短整数存储做准备
    */
                     CArrayShort(void);

   /**
    * @brief 析构函数：销毁 CArrayShort 类实例
    * @details 调用 Shutdown 方法释放数组占用的内存，避免内存泄漏
    */
                    ~CArrayShort(void);

   //--- 对象类型识别方法
   /**
    * @brief 获取当前数组对象的类型标识
    * @return int - 类型标识，固定返回 TYPE_SHORT（表示16位短整数类型数组）
    */
   virtual int       Type(void) const { return(TYPE_SHORT); }

   //--- 文件操作相关方法
   /**
    * @brief 将数组中的短整数数据写入指定文件（按 SHORT_VALUE 格式存储）
    * @param file_handle [in] 已打开的文件句柄（需提前通过 FileOpen 创建，权限包含写入）
    * @return bool - 操作结果：true 表示写入成功，false 表示写入失败（如文件句柄无效、写入异常）
    */
   virtual bool      Save(const int file_handle);

   /**
    * @brief 从指定文件读取短整数数据到数组（按 SHORT_VALUE 格式读取）
    * @param file_handle [in] 已打开的文件句柄（需提前通过 FileOpen 创建，权限包含读取）
    * @return bool - 操作结果：true 表示读取成功，false 表示读取失败（如文件句柄无效、格式错误）
    */
   virtual bool      Load(const int file_handle);

   //--- 动态内存管理方法
   /**
    * @brief 为数组预留指定大小的空闲内存空间
    * @details 检查当前剩余空闲空间，不足时按预设步长扩容，减少频繁内存分配的性能开销（短整数数组内存占用低，扩容成本小）
    * @param size [in] 需要预留的空闲元素数量（非总容量，仅新增空闲空间）
    * @return bool - 操作结果：true 表示预留成功，false 表示预留失败（如 size≤0 或内存分配失败）
    */
   bool              Reserve(const int size);

   /**
    * @brief 调整数组总容量（超出容量的元素会被截断删除）
    * @param size [in] 调整后的数组总容量（包含已存储元素和空闲空间）
    * @return bool - 操作结果：true 表示调整成功，false 表示调整失败（如 size<0 或内存分配失败）
    */
   bool              Resize(const int size);

   /**
    * @brief 彻底清空数组并释放所有占用的内存
    * @details 重置数组数据、总容量、已存储元素数量等成员变量，将内存归还给系统
    * @return bool - 操作结果：true 表示清理成功，false 表示清理失败（如内存释放异常）
    */
   bool              Shutdown(void);

   //--- 数组填充相关方法
   /**
    * @brief 向数组末尾添加一个16位短整数元素
    * @param element [in] 要添加的 short 类型元素（取值范围：-32768 ~ 32767，超出范围会自动截断）
    * @return bool - 操作结果：true 表示添加成功，false 表示添加失败（如内存不足）
    */
   bool              Add(const short element);

   /**
    * @brief 将外部 short 数组的所有元素添加到当前数组末尾
    * @param src [in] 外部 short 类型数组（需传入数组引用，确保数组有效）
    * @return bool - 操作结果：true 表示添加成功，false 表示添加失败（如内存不足）
    */
   bool              AddArray(const short &src[]);

   /**
    * @brief 将另一个 CArrayShort 实例的所有元素添加到当前数组末尾
    * @param src [in] 指向另一个 CArrayShort 实例的指针（需先通过 CheckPointer 验证有效性）
    * @return bool - 操作结果：true 表示添加成功，false 表示添加失败（如指针无效、内存不足）
    */
   bool              AddArray(const CArrayShort *src);

   /**
    * @brief 在数组指定索引位置插入一个16位短整数元素
    * @details 插入位置及后续元素自动后移，数组已存储元素数量（长度）加 1
    * @param element [in] 要插入的 short 类型元素（注意取值范围限制）
    * @param pos [in] 插入位置的索引（从 0 开始，需满足 0≤pos≤当前数组长度）
    * @return bool - 操作结果：true 表示插入成功，false 表示插入失败（如位置无效、内存不足）
    */
   bool              Insert(const short element,const int pos);

   /**
    * @brief 将外部 short 数组的所有元素插入到当前数组指定位置
    * @details 插入位置及后续元素自动后移，数组长度增加外部数组的元素个数
    * @param src [in] 外部 short 类型数组（需传入数组引用）
    * @param pos [in] 插入位置的索引（从 0 开始，需满足 0≤pos≤当前数组长度）
    * @return bool - 操作结果：true 表示插入成功，false 表示插入失败（如位置无效、内存不足）
    */
   bool              InsertArray(const short &src[],const int pos);

   /**
    * @brief 将另一个 CArrayShort 实例的所有元素插入到当前数组指定位置
    * @details 插入位置及后续元素自动后移，数组长度增加源实例的元素个数
    * @param src [in] 指向另一个 CArrayShort 实例的指针（需验证指针有效性）
    * @param pos [in] 插入位置的索引（从 0 开始，需满足 0≤pos≤当前数组长度）
    * @return bool - 操作结果：true 表示插入成功，false 表示插入失败（如指针无效、位置无效）
    */
   bool              InsertArray(const CArrayShort *src,const int pos);

   /**
    * @brief 用外部 short 数组的内容覆盖当前数组（赋值操作）
    * @details 先清空当前数组所有元素，再将外部数组的元素完整复制到当前数组
    * @param src [in] 外部 short 类型数组（需传入数组引用）
    * @return bool - 操作结果：true 表示赋值成功，false 表示赋值失败（如内存不足）
    */
   bool              AssignArray(const short &src[]);

   /**
    * @brief 用另一个 CArrayShort 实例的内容覆盖当前数组（赋值操作）
    * @details 先清空当前数组所有元素，再复制源实例的元素和排序状态到当前数组
    * @param src [in] 指向另一个 CArrayShort 实例的指针（需验证指针有效性）
    * @return bool - 操作结果：true 表示赋值成功，false 表示赋值失败（如指针无效、内存不足）
    */
   bool              AssignArray(const CArrayShort *src);

   //--- 数组元素访问方法
   /**
    * @brief 获取数组指定索引位置的16位短整数元素
    * @param index [in] 要访问的元素索引（从 0 开始，需满足 0≤index<当前数组长度）
    * @return short - 对应索引的短整数元素；若索引无效，返回 SHORT_MAX（16位短整数的最大值，代表无效值）
    */
   short             At(const int index) const;

   /**
    * @brief 重载 [] 运算符，通过索引直接访问数组元素（等价于 At 方法）
    * @param index [in] 要访问的元素索引（从 0 开始，需满足 0≤index<当前数组长度）
    * @return short - 对应索引的短整数元素；若索引无效，返回 SHORT_MAX
    */
   short operator[](const int index) const { return(At(index)); }

   //--- 最小值/最大值查找方法
   /**
    * @brief 在数组指定范围内查找最小短整数的索引
    * @param start [in] 查找范围的起始索引（从 0 开始）
    * @param count [in] 查找的元素个数（需满足 start + count ≤ 当前数组长度）
    * @return int - 最小短整数所在的索引；若范围无效，返回 -1
    */
   int               Minimum(const int start,const int count) const { return(CArray::Minimum(m_data,start,count)); }

   /**
    * @brief 在数组指定范围内查找最大短整数的索引
    * @param start [in] 查找范围的起始索引（从 0 开始）
    * @param count [in] 查找的元素个数（需满足 start + count ≤ 当前数组长度）
    * @return int - 最大短整数所在的索引；若范围无效，返回 -1
    */
   int               Maximum(const int start,const int count) const { return(CArray::Maximum(m_data,start,count)); }

   //--- 数组元素修改方法
   /**
    * @brief 更新数组指定索引位置的16位短整数元素
    * @param index [in] 要更新的元素索引（需满足 0≤index<当前数组长度）
    * @param element [in] 新的 short 类型元素（取值范围：-32768 ~ 32767，超出范围会自动截断）
    * @return bool - 操作结果：true 表示更新成功，false 表示更新失败（如索引无效）
    */
   bool              Update(const int index,const short element);

   /**
    * @brief 将数组指定索引的元素按指定偏移量移动位置
    * @param index [in] 要移动的元素原始索引（需在有效范围内）
    * @param shift [in] 偏移量（正数表示向后移动，负数表示向前移动，需确保移动后位置有效）
    * @return bool - 操作结果：true 表示移动成功，false 表示移动失败（如位置越界、偏移量为 0）
    */
   bool              Shift(const int index,const int shift);

   //--- 数组元素删除方法
   /**
    * @brief 删除数组指定索引位置的元素
    * @details 删除后，后续元素自动前移，数组长度减 1
    * @param index [in] 要删除的元素索引（需满足 0≤index<当前数组长度）
    * @return bool - 操作结果：true 表示删除成功，false 表示删除失败（如索引无效）
    */
   bool              Delete(const int index);

   /**
    * @brief 删除数组中指定范围的元素（闭区间 [from, to]）
    * @details 删除后，后续元素自动前移，数组长度减少（to - from + 1）
    * @param from [in] 删除范围的起始索引（需≥0）
    * @param to [in] 删除范围的结束索引（需≥from 且 < 当前数组长度）
    * @return bool - 操作结果：true 表示删除成功，false 表示删除失败（如范围无效）
    */
   bool              DeleteRange(int from,int to);

   //--- 数组比较方法
   /**
    * @brief 比较当前数组与外部 short 数组是否完全相等
    * @details 需满足“元素个数相同”且“对应位置的短整数严格相等”（短整数无精度误差，直接 == 判定）
    * @param array [in] 要比较的外部 short 类型数组（需传入数组引用）
    * @return bool - 比较结果：true 表示完全相等，false 表示不相等（如长度不同、元素不匹配）
    */
   bool              CompareArray(const short &array[]) const;

   /**
    * @brief 比较当前数组与另一个 CArrayShort 实例是否完全相等
    * @details 需满足“元素个数相同”且“对应位置的短整数严格相等”（短整数无精度误差）
    * @param array [in] 指向要比较的 CArrayShort 实例的指针（需验证指针有效性）
    * @return bool - 比较结果：true 表示完全相等，false 表示不相等（如指针无效、长度不同）
    */
   bool              CompareArray(const CArrayShort *array) const;

   //--- 有序数组操作方法（需数组已排序，否则方法返回无效结果）
   /**
    * @brief 向有序数组中插入元素（保持数组升序/降序特性）
    * @param element [in] 要插入的 short 类型元素
    * @return bool - 操作结果：true 表示插入成功（数组保持有序），false 表示插入失败（如数组未排序）
    */
   bool              InsertSort(const short element);

   /**
    * @brief 在有序数组中查找指定短整数元素的索引
    * @details 短整数比较无精度误差，找到时返回精确匹配的元素索引
    * @param element [in] 要查找的 short 类型元素
    * @return int - 查找结果：找到时返回元素索引，未找到或数组未排序返回 -1
    */
   int               Search(const short element) const;

   /**
    * @brief 在有序数组中查找第一个大于指定短整数的元素索引
    * @param element [in] 参考的 short 类型元素
    * @return int - 查找结果：找到时返回对应索引，未找到（如所有元素均≤目标）或数组未排序返回 -1
    */
   int               SearchGreat(const short element) const;

   /**
    * @brief 在有序数组中查找第一个小于指定短整数的元素索引
    * @param element [in] 参考的 short 类型元素
    * @return int - 查找结果：找到时返回对应索引，未找到（如所有元素均≥目标）或数组未排序返回 -1
    */
   int               SearchLess(const short element) const;

   /**
    * @brief 在有序数组中查找第一个大于或等于指定短整数的元素索引
    * @param element [in] 参考的 short 类型元素
    * @return int - 查找结果：找到时返回对应索引，未找到或数组未排序返回 -1
    */
   int               SearchGreatOrEqual(const short element) const;

   /**
    * @brief 在有序数组中查找第一个小于或等于指定短整数的元素索引
    * @param element [in] 参考的 short 类型元素
    * @return int - 查找结果：找到时返回对应索引，未找到或数组未排序返回 -1
    */
   int               SearchLessOrEqual(const short element) const;

   /**
    * @brief 在有序数组中查找指定短整数第一次出现的索引
    * @param element [in] 要查找的 short 类型元素（数组中可能存在多个相同值）
    * @return int - 查找结果：找到时返回第一次出现的索引，未找到或数组未排序返回 -1
    */
   int               SearchFirst(const short element) const;

   /**
    * @brief 在有序数组中查找指定短整数最后一次出现的索引
    * @param element [in] 要查找的 short 类型元素（数组中可能存在多个相同值）
    * @return int - 查找结果：找到时返回最后一次出现的索引，未找到或数组未排序返回 -1
    */
   int               SearchLast(const short element) const;

   /**
    * @brief 对数组进行线性查找（遍历数组，适用于无序数组）
    * @details 逐个比较元素与目标值，找到时返回第一个精确匹配的索引
    * @param element [in] 要查找的 short 类型元素
    * @return int - 查找结果：找到时返回第一个匹配元素的索引，未找到返回 -1
    */
   int               SearchLinear(const short element) const;

protected:
   /**
    * @brief 快速排序算法：对数组指定范围元素进行排序（内部使用，不对外暴露）
    * @param beg [in] 排序范围的起始索引（需≥0）
    * @param end [in] 排序范围的结束索引（需≥beg 且 < 当前数组容量）
    * @param mode [in] 排序模式（默认 0，通常表示升序，具体逻辑继承自父类 CArray）
    */
   virtual void      QuickSort(int beg,int end,const int mode=0);

   /**
    * @brief 快速查找算法：在有序数组中定位元素位置（内部使用，为 Search 系列方法提供支持）
    * @details 基于二分法实现，返回精确匹配或近似位置的索引
    * @param element [in] 要查找的 short 类型元素
    * @return int - 查找的位置索引（若找到则为匹配元素索引，未找到则为最后比较的中间位置）
    */
   int               QuickSearch(const short element) const;

   /**
    * @brief 数组内部内存移动：将指定范围元素从源位置复制到目标位置（内部使用）
    * @details 用于插入、删除等操作时的元素位置调整，避免内存碎片（短整数数组复制效率高）
    * @param dest [in] 目标位置的起始索引（需≥0）
    * @param src [in] 源位置的起始索引（需≥0）
    * @param count [in] 要移动的元素个数（需满足 src + count ≤ 当前数组长度）
    * @return int - 操作结果：成功返回目标位置起始索引，失败返回 -1
    */
   int               MemMove(const int dest,const int src,int count);
  };
//+------------------------------------------------------------------+